home *** CD-ROM | disk | FTP | other *** search
/ Carousel / CAROUSEL.cdr / mactosh / lang / lsc30p4u.sit / IMPORTANT - READ THIS! next >
Text File  |  1989-01-16  |  5KB  |  128 lines
  1.  
  2. Change in Exit Handling
  3. 1/16/89
  4.  
  5. It is IMPERATIVE that you apply the library changes, included in this
  6. package, when you apply the 3.01p4 patch.  The old libraries are
  7. incompatible with the new compiler.
  8.  
  9. Also, this memo contains critical information concerning the behavior of
  10. your application when it exits.  This is information which you MUST KNOW
  11. if:
  12.  
  13.     (1a) You call the standard library function "onexit", or you use
  14.          stdio, the profiler, or "signal" (each of which calls "onexit").
  15.  
  16.                                 -or-
  17.  
  18.     (1b) You build applications with the "Separate STRS" option set.
  19.          (This option is frequently set in projects which originated
  20.          prior to THINK C 3.0.)
  21.     
  22.                                 -and-
  23.  
  24.     (2)  Your application can exit by calling "Launch" (or "_Launch").
  25.          (For example, your application may implement a "Transfer"
  26.          menu.)
  27.  
  28. If you don't use "Launch", or you don't use "onexit" or "Separate STRS",
  29. then you can get away without reading the rest of this.  But please be
  30. sure to update your libraries no matter what!
  31.  
  32.  
  33. BACKGROUND
  34. ----------
  35.  
  36. The manner in which THINK C applications clean up when they exit has
  37. changed in version 3.01p4.  When using this version (or later), it is
  38. critical that you avoid using earlier versions of the standard libraries,
  39. as the implementation of "onexit" has changed in an incompatible way.
  40.  
  41. In addition, it can no longer be guaranteed that your application will
  42. be able to clean up if it exits with a "Launch".  This may be an issue
  43. if you are relying on "onexit" to schedule clean-up.  Even if you're not
  44. using "onexit", the runtime system for applications built with "Separate
  45. STRS" has clean-up of its own to perform at exit.
  46.  
  47. Previously, the runtime system built into every THINK C application was
  48. able to arrange for clean-up no matter how the application might exit.
  49. Unfortunately, the method used to assure this resulted in applications
  50. which were not "32-bit clean".
  51.  
  52. The new method is 32-bit clean, but can't catch the case where the
  53. application exits with a "Launch".  (Actually, even this case is caught
  54. if the application is running under MultiFinder -- though this can't be
  55. guaranteed for future versions of MultiFinder.)
  56.  
  57.  
  58. WAYS OF EXITING
  59. ---------------
  60.  
  61. Let's define some terms:
  62.  
  63.     "normal exit"
  64.     
  65.         If your application exits by calling the "exit" function, or
  66.         by returning from "main", this is considered a normal exit.
  67.     
  68.     "abnormal exit"
  69.     
  70.         If your application exits by calling "ExitToShell", this is
  71.         considered an abnormal exit.  Calling "abort" is covered under
  72.         this definition, as is terminating execution under the control
  73.         of a debugger.  (Under the CURRENT implementation of MultiFinder,
  74.         all exits are either normal or abnormal -- even "SysError" ends
  75.         up calling "ExitToShell"!)
  76.     
  77.     "unsafe exit"
  78.     
  79.         If your application exits by calling "Launch", or in any other
  80.         manner not covered above, this is considered an unsafe exit.
  81.  
  82.  
  83. ONEXIT AND _ONEXIT
  84. ------------------
  85.  
  86. Routines registered with "onexit" will now be called only on normal exits.
  87. Previously, they were called on any form of exit.
  88.  
  89. A new routine, "_onexit", is now available.  Routines registered with
  90. "_onexit" will be called on abnormal as well as normal exits.
  91.  
  92. To summarize:
  93.  
  94.     (1) On a normal exit, routines registered with "onexit" or
  95.         "_onexit" will be called.
  96.     
  97.     (2) On an abnormal exit, routines registered with "_onexit"
  98.         will be called.  Routines registered with "onexit" will
  99.         NOT be called.
  100.  
  101. In both of these cases, the runtime support for "Separate STRS" will be
  102. given a chance to clean up.  (This happens even if you never register any
  103. clean-up routines of your own.)
  104.  
  105.  
  106. DEALING WITH UNSAFE EXITS
  107. -------------------------
  108.  
  109. If an unsafe exit is taken, no clean-up routines will be called.  If you
  110. have registered essential clean-up routines (e.g. removing trap intercepts
  111. or other low-memory vectors), or if your application is built using
  112. "Separate STRS", this could be disastrous.
  113.  
  114. To deal with this, a new routine, "_exiting", is now available.  This
  115. function performs all appropriate clean-up, but doesn't actually exit.
  116. It should be called before initiating an unsafe exit, e.g. before calling
  117. "Launch".
  118.  
  119. "_exiting" takes an argument indicating whether the clean-up should be
  120. that associated with a normal or an abnormal exit.  A non-zero argument
  121. indicates a normal exit.
  122.  
  123. If your application never calls "onexit" or "_onexit" (and doesn't use
  124. stdio, the profiler, or "signal", which do), AND if your application is
  125. not built with "Separate STRS", then you needn't bother with "_exiting".
  126.  
  127. The "exec" series of standard library functions call "_exiting(1)".
  128.